home *** CD-ROM | disk | FTP | other *** search
/ Aminet 4 / Aminet 4 - November 1994.iso / aminet / dev / m2 / m2_part1.lha / modula / dice / dice.LHA / doc / COMPILER.DOC < prev    next >
Text File  |  1991-03-28  |  14KB  |  343 lines
  1.  
  2. compiler/compiler                        compiler/compiler
  3. compiler/COMPILER                        compiler/COMPILER
  4.  
  5.                 DICE SYSTEM
  6.  
  7.                   Matthew Dillon
  8.                   891 Regal Rd.
  9.                   Berkeley, Ca. 94708
  10.                   USA
  11.  
  12.                   dillon@overload.Berkeley.CA.US
  13.                   uunet.uu.net!overload!dillon
  14.  
  15.                   BIX: mdillon
  16.  
  17.             COMPILER FEATURES LIST AND ORGANIZATION
  18.  
  19.             NOTE: net distributed releases will not contain
  20.               commodore includes or amiga*.lib
  21.  
  22.     (1) Organization of includes and libraries, default:
  23.  
  24.     DINCLUDE:        location of top level includes such as stdio.h
  25.     DINCLUDE:Amiga/     location of amiga includes (e.g. amiga/exec/types.h)
  26.                 (amiga includes not included)
  27.  
  28.     NOTE !!! Amiga includes should be placed in the subdirectory
  29.     dinclude:Amiga, that is, dinclude:Amiga/Exec/*.h,
  30.     dinclude:Amiga/graphics/*.h, etc...
  31.  
  32.     DCC references startup and libraries to DLIB:
  33.  
  34.     DLIB:amigas.lib     A small-data model version of AMIGA.LIB
  35.     DLIB:c.lib        The main C library for which you have source code
  36.     DLIB:m.lib        The math library
  37.     DLIB:auto.lib        The auto library-open library
  38.     DLIB:c.o        The startup module
  39.     DLIB:x.o        The terminator module
  40.  
  41.     (2) Organization of includes and libraries, -2.0 option (usually
  42.     set in the DCCOPTS enviroment variable)
  43.  
  44.     DINCLUDE:AMIGA20/   instead of DINCLUDE:AMIGA
  45.     DLIB:amigas20.lib   instead of DLIB:amigas.lib
  46.  
  47.  
  48.     (3) DCC generated link lines
  49.  
  50.     If you give DICE the following line:
  51.  
  52.     1> DCC foo.o -o foo
  53.  
  54.     It will run DLink with the following options:
  55.  
  56.     DLink dlib:c.o foo.o dlib:c.lib dlib:amigas.lib dlib:auto.lib dlib:x.o -o foo
  57.  
  58.     DLIB:C.O        DICE startup code
  59.     FOO.O        your object module(s)
  60.     DLIB:C.LIB        DICE C.LIB
  61.     DLIB:AMIGAS.LIB    small data model version of commodore amiga.lib
  62.     DLIB:AUTO.LIB    DICE AUTO.LIB
  63.     DLIB:X.O        DICE section terminator code
  64.  
  65.  
  66.     Some explanation is in order.  AUTO.LIB catches any references
  67.     to common library base variables when no storage has been
  68.     declared and imports code to automatically open said libraries
  69.     on startup and close them on exit.  DICE uses this feature to
  70.     import code to open and close "dos.library" when DOSBase is
  71.     referenced, and also for the floating point libraries.
  72.  
  73.     X.O is used to supply an RTS at the end of the special autoinit
  74.     and autoexit sections.    Any module between C.O and X.O may
  75.     declare these special sections to handle run-time relocations and
  76.     other DICE features, and do so such that when the base of the
  77.     section is JSR'd all the various module's code is sequenced
  78.     through until the RTS in X.O is hit for the sections in
  79.     question.
  80.  
  81.  
  82.     (4) SMALL DATA AMIGA.LIB
  83.  
  84.     DICE uses a small-data model version of Commodore's AMIGA.LIB
  85.     to allow it to generate residentable executables (-r option to
  86.     DCC).  The small data amiga.lib, called AMIGAS.LIB (note the 's')
  87.     is generated from the large modem amiga.lib with the LIBTOS
  88.     program.
  89.  
  90.     LIBTOS, including source, is included.    The source is available
  91.     to allow developers using DICE to add new base variables to
  92.     LIBTOS's search list when new operating systems come out without
  93.     having to wait for my update.
  94.  
  95.  
  96.     ----------------------------------------------------------------------
  97.  
  98.                 COMPILER FEATURES LIST
  99.  
  100.     (0) ANSI.  Pretty much ansi.  Please report non-ansism problems.  Check
  101.     out the doc/KnownBugs list before reporting a problem.
  102.  
  103.     (1) autos are placed in registers based on weighted usage.  A0,A1,D0,D1
  104.     will be used as register variables whenever possible, which usually
  105.     reduces the number of registers that must be saved/restored in
  106.     critical low level routines.  The 'register' keyword is
  107.     essentially ignored (use 'volatile' to force a variable to NOT
  108.     be in a register).
  109.  
  110.     (2) LINK/UNLK is removed from low level routines that do not reference
  111.     A5 and do not make any subroutine calls.
  112.  
  113.     (3) MOVEM is converted to MOVE or deleted entirely when possible.
  114.  
  115.     (4) Various obvious optimizations:  use of BSET, BCLR, BTST as short
  116.     cuts to logic operations, CMP/TST, etc...
  117.  
  118.     (5) Switch() statements are optimized as follows:
  119.  
  120.         * if the range of values is less than double the number of cases
  121.           a lookup table will be used
  122.  
  123.         * if a small number of cases exists a sub[q]/beq sequence
  124.           will be used
  125.  
  126.         * for a sufficiently large set of cases that cannot be made
  127.           into a jump table, a binary subdivision method is used.
  128.  
  129.     (6) Branch optimization.  Bxx to BRAs are optimized (up to 20 hops) by
  130.     DAS, and massive optimization is done to multi-level conditionals
  131.     by the main compiler pass.
  132.  
  133.     (7) Workbench support.  The standard startup module supports the workbench.
  134.     Specifically, the low level _main() in c.o does this.
  135.  
  136.     When a program is run from the workbench, a different entry point is
  137.     called:     wbmain(wbmsg)
  138.  
  139.     If you do not supply a wbmain() then the one from the c.lib library
  140.     is used which immediately return(-1)s, exiting the program.
  141.  
  142.     The standard return from wbmain() or using exit() or _exit()
  143.     automatically ReplyMsg()s the workbench message for you, do NOT
  144.     do so manually.
  145.  
  146.     (8) _main() shortcut for extremely low level programs.
  147.  
  148.     REFER TO _MAIN.DOC FOR INFORMATION ON USING THE _main()
  149.     ENTRY POINT INSTEAD OF main().
  150.  
  151.     (9) AutoInit support.  You may qualify a subroutine with the __autoinit
  152.     keyword that will cause it to be automatically called by the
  153.     startup code rather than having to explicitly call it from main.
  154.  
  155.     This feature is more useful to bring code in indirectly.  For
  156.     example, to automatically OpenLibrary() (& CloseLibrary()) floating
  157.     point libraries if their base variables are referenced.
  158.  
  159.     Refer to the auto.lib source code for examples.
  160.  
  161.     __autoexit works the same way.    Note that __autoinit routines are
  162.     called BEFORE _main, just after autoinit libraries are openned,
  163.     and __autoexit routines are called in __exit just before autoinit
  164.     libraries are closed.
  165.  
  166.     (10) DCC runs fast.  Make everything resident and watch it fly.  Most
  167.      of this speed comes from loading entire files into memory at once.
  168.      This might present a memory problem, but in general DICE's memory
  169.      usage is comparable to Lattice and Aztec.
  170.  
  171.     (11) CODE SIZE is comparable with Lattice and Aztec, even better in
  172.      many cases.  The minimum program sizes are as follows:
  173.  
  174.     _main() { }          448    no stdio/fd
  175.      main() { }         2736    some stdio
  176.      main() { printf..} 5492    most of stdio
  177.  
  178.     (12) EXTENSIONS , see EXTENSIONS.DOC.  DICE provides many extensions
  179.      to C to support various AMIGAisms and ROM based code, including
  180.      special treatment of the 'const' storage qualifier.
  181.  
  182.     (13) The preprocessor is able to handle arbitrarily sized macros.  There
  183.      are no limits to symbol or macro length.  The preprocessor is able to
  184.      handle up to 64 levels of includes / macro recursions with arbitrary
  185.      use of the string-ize (#) and token pasting (##) operators.
  186.  
  187.      The preprocessor implements the __BASE_FILE__ macro as well as all
  188.      standard ANSI macros (__FILE__, __LINE__, __DATE__, __TIME__, ...)
  189.  
  190.     (14) DICE supports the creation of residentable executables in nearly
  191.      all cases (exception: using the __geta4 procedure qualifier
  192.      precludes being able to make an executable resident, also non
  193.      const __chip data).
  194.  
  195.      Not only is residentability supported, but it is supported
  196.      without requiring the programmer to #include all sorts of
  197.      prototype/pragma files.
  198.  
  199.     (15) DICE supports the small-data model, large data model, small and
  200.      large code models, and special data models (word absolute,
  201.      absolute known address) for supporting ROMable code.  The linker
  202.      automatically generates JMP tables when the small-code model is
  203.      used in large executables.
  204.  
  205.     (16) REGISTERED user's DICE supports __chip, __near, and __far keywords,
  206.      as well as others.
  207.  
  208.     (17) Simplified library and startup module design.  There are no multiple
  209.      versions of a single library for different memory models and the
  210.      frontend, DCC, makes all library and startup module interaction
  211.      except m.lib invisible.  The same c.o handles both resident and
  212.      non-resident startup.    c.lib and m.lib may be used with programs
  213.      that declare more than 64KBytes of BSS (though not with programs
  214.      that declare more than 64KBytes of __near initialized storage).
  215.  
  216.      There is no large-data-model version of c.lib and m.lib,
  217.      although you can easily recompile the libraries into a large-data
  218.      model version if you wish.  I suggest that instead of doing that
  219.      you stick with the small-data model and use the __geta4 type
  220.      qualifier to procedures which are called out of context.
  221.  
  222.     (18) Optimization of args to prototyped routines
  223.  
  224.  
  225.     --------------------------------------------------------------------------
  226.                     GOALS
  227.  
  228.     In writing DICE my goals are as follows:
  229.  
  230.     - reasonably fast compilation.  Modular executables for ease of use,
  231.       reliability, and testability.
  232.  
  233.     - concentrate more on reliability and less on optimizations.  Remember that
  234.       this is only the third major distribution of DICE, I expect some bugs
  235.       to show up.  I expect to become more reliable than the two other
  236.       commercial C compilers in the Amiga market within a year.
  237.  
  238.     - but do not forget optimizations... put in relatively easy to implement
  239.       optimizations that do not destroy the reliability of DICE.  DICE does
  240.       no common sub-expression or loop unrolling optimizations, but does do
  241.       relatively smart register allocation and multi-level history to
  242.       propogate conditional expressions.
  243.  
  244.     - provide comprehensive support of the Amiga, especially for new
  245.       versions of the OS that come out.
  246.  
  247.     - I have always torn my hair out at not being able to easily fix bugs in
  248.       the support libraries for commercial compilers.  DICE includes full
  249.       source for its support libraries (c.lib, m.lib, auto.lib) and a means
  250.       to remake the library.  DICE also includes full source to some of
  251.       its own utilities, namely LIBTOS and the DCC frontend which are the
  252.       most likely candidates for programmer hair loss.
  253.  
  254.     ------------------------------------------------------------------------
  255.                    COMMENTS
  256.  
  257.     Registerized parameters are not implemented.  While such a feature
  258.     would make an executable somewhat smaller and a little faster, a few
  259.     percent of gain is not worth the complexity of the implementation (and
  260.     thus the possibility of introduced bugs).  The difference in execution
  261.     speed is generally so miniscule that it isn't noticable, and where it
  262.     is noticable it is usually due to a badly implemented algorithm in
  263.     the first place.
  264.  
  265.     So, cute, but not as much of a boost as you might think.
  266.  
  267.     Inline library calls are not implemented either.  Inline library calls
  268.     are actually useful and when properly implemented increase efficiency
  269.     to low level calls such as AddHead() and GetMsg().  Other calls such as
  270.     Move() and Draw() do not increase noticably in efficiency. #pragma's
  271.     must be used to define inline calls and this makes the compiler
  272.     enviroment less portable.  Lattice made a big mistake *requiring* the
  273.     use of inline library calls with residentable programs.  My solution
  274.     was to write a program to convert AMIGA.LIB into a small-data version
  275.     of same called AMIGAS.LIB.
  276.  
  277.     In general, I refuse to implement a thousand nearly useless features
  278.     that will only introduce more bugs into the compiler.
  279.  
  280.     ------------------------------------------------------------------------
  281.                 COMPATIBILITY
  282.  
  283.                    ANSI C
  284.  
  285.     DICE is getting closer to being ANSI C compliant, there are only a
  286.     few things missing.
  287.  
  288.     I spent a great deal of time ensuring that STDIO routines run relatively
  289.     fast.  I decided to write nearly all of the support library in C instead
  290.     of falling back to optimized assembly to keep the system uniform and
  291.     portable.  One does not notice much of a difference between the C
  292.     strcpy() and an assembly strcpy() relative to the run time of their
  293.     program.
  294.  
  295.                     AMIGA
  296.  
  297.     As said in feature (7), if you wish your program to be runnable from
  298.     the workbench you must supply a wbmain() entry point.  If you do not
  299.     then running the program from the workbench will result in its
  300.     immediate termination (e.g. nothing happens).  On return from wbmain()
  301.     or exit() the workbench message is automatically ReplyMsg()d by the
  302.     exit code.
  303.  
  304.     DICE separates workbench startup and puts it in the hands of the user
  305.     to simplify the user's code.  Since there are two entry points,
  306.     main() for CLI run programs and wbmain() for WORKBENCH-run programs,
  307.     the programmer can more easily modularize his code.
  308.  
  309.     The Registered release of DICE supports the __near, __far, and __chip
  310.     keywords.
  311.  
  312.                   UNBUFFERED CONSOLE IO
  313.  
  314.     You may set a console to RAW mode using the setbuf() and setvbuf() calls.
  315.     You may set a console back to COOKED mode using the same calls.
  316.  
  317.     ------------------------------------------------------------------------
  318.  
  319.                 Your first program
  320.  
  321.     1> cd examples
  322.     1> dcc hello.c -o ram:hello
  323.     1> ram:hello
  324.     hello world
  325.     1>
  326.  
  327.                 Your first residentable program
  328.  
  329.     1> cd examples
  330.     1> dcc hello.c -o ram:hello -r
  331.     1> ram:hello
  332.     hello world
  333.     1> resident ram:hello
  334.     1> hello        ; instantanious execution
  335.     hello world
  336.     1>
  337.  
  338.     * NOTE, a common problem is that users have removed various floating
  339.     point libraries from LIBS: and this will prevent DC1 from running.
  340.     Make sure you have the full complement of floating point libraries
  341.     in LIBS:
  342.  
  343.